COMMENT ⊗   VALID 00004 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	Guide to vision routines on [VIS,HPM]
C00008 00003	VIXHDR.SAI   for displaying grey scale and halftone pictures on data disc.
C00012 00004	Internal picture array format
C00014 ENDMK
C⊗;
Guide to vision routines on [VIS,HPM]

PIXHDR.SAI   utility routines for getting, saving, moving, etc. pictures

	requires: PIXFAI.REL,PIXSAI.REL

	provides:
		  PCLN,PCWD,PCBY,PCBYA,LNWD,LNBY,	where to find things in
		  LNBYA,WDBY,WDBI,BYBI,BPTAB,LINTAB	picture arrays


	VALUE  ←  PIXEL(PICTURE,ROW,COLUMN);		value of a particular pixel
		  PUTEL(PICTURE,ROW,COLUMN,VALUE);	change a pixel
		  ADDEL(PICTURE,ROW,COLUMN,VALUE);	increment a pixel

        SIZE   ←  PFLDIM(FILNAME);		size of array needed for pic file
        SIZE   ←  GETPFL(FILNAME,PICTURE);		read in a pic file
		  PUTPFL(PICTURE,FILENAME);		write out PICTURE

        SIZE   ←  PIXDIM(HEIGHT,WIDTH,BITS);	size of array for HxWxB picture
        SIZE   ←  MAKPIX(HEIGHT,WIDTH,BITS,PICTURE); make skeleton HxWxB picture
                  WIPE(PICTURE,VALU(0)); make every data word (not byte!) =VALU

                  pixtrn(src,tr,dest); transforms src into dst by array tr.
                     tr is a 3x3 real array. For all pixels (y,x) in dest
                     set (ty,tx,foo) ← (y,x,1) * transform. if (ty,tx) is
                     in src then dest(y,x) ← src(ty,tx);

		  COPPIC(PICTURE1,PICTURE2);  copy pic1 to pic2
		  HAFPIC(PICTURE1,PICTURE2,MAXBIT);  reduce pic to half resolution
		  SHRINK(PICT1,PICT2);        squeeze or expand PICT1 into PICT2
		  SELECT(PICTURE1,YEDGE,XEDGE,PICTURE2);  take a piece of a pic

                  PICADD(PICTURE,PICSUM);     add a picture to a picture
		  PICSH(PIC1,PIC2,DIV);       every pixel in PIC1/DIV→PIC2

		  GRAY(PIC);	Convert to gray code.
		  UNGRAY(PIC);	Convert back.

        NRETRY ←  CAMPIX(CAMERA,YEDGE,XEDGE,PICTURE,
                    SUMS(1),BCLIP(7),TCLIP(0),MAXTRY(20)); read from a camera
        NRETRY ←  CLPADJ(CAM,BLCIP,TCLIP); find optimum clip levels for CAM
        NRETRY ←  TVSNAP(CAM,YEDG,XEDG,PIC,BCLIP,TCLIP,NTRY); primitive camera
        NRETRY ←  TVRAW(CAM,YEDG,XEDG,PIC,BCLIP,TCLIP,NTRY); routines, used by
                  TVBTMX(PIC4,PICN,XFRM);		     CAMPIX

       SUM     ←  INTOP(PIC,WINSIZE,ANSARRY,YEDGE(0),XEDGE(0));interest operator
                  INTLOM(HIG,WID,ANSARRY); intop local max operator
       SIZE    ←  INTERESTDIM(PICTURE,WINDOWSIZE);  pic size needed for intrst op
		  INTEREST(PICTURE,WINDOW,RESULTPICTURE); make interest op picture

       BESTVAL ←  MATCH(PICTURE1,SY1,SX1,SY2,SX2, PICTURE2,DY1,DX1,DY2,DX2);
       BSTCOEF ←  NORCOR(PICTURE1,SY1,SX1,SY2,SX2, PICTURE2,DY1,DX1,DY2,DX2);
                   ;correlators, find Source window in pic1 in Dest in pic2

		  CLEAN(PICTURE);	remove single pixel noise, blurs a little
		  PASSHI(PICTURE1,WINDOWSIZE,PICTURE2);   high pass filter
        SUM    ←  CMPPAR(PICTURE1,PICTURE2);  compare two pics [ sig(x-y)↑2 ]

		  PERBIT(PICTURE, TRANSFORM); transform each pixel of pic
		  HISTOG(PICTURE, HISTOGRAM); count # of occurences of each gray val
		  ENHANCE(PICTURE);	      make histogram flat
		  SYNCHRONIZE(PICTURE1);      do a vertical roll fixup

		  ROWSUM(PICTURE1,ROWSUMS);   sum up the pixels in each row
		  ROWSUD(PICTURE1,ROWSUMS);   dirty rowsums, one pixel/word used
		  COLSUM(PICTURE1,COLSUMS);   sum up the pixels in each col
	MASS	← CENTRO(PIC,YL,XL,XH,XH,THR); centroid and moment of a dark area

                  UNPACK(SOURCEARRAY, PICTURE);   copy a pict into a full wd array
		  GETPAR(ARRY, PICTR);	      copy full word array of pixels to pic

		  EDGEINIT(PICTURE,SIZE);	initialize edge operator
                  EDGE(X,Y,EDGERESULT);		apply edge operator

	NOTE: all picture and other arrays are zero origin in all dimensions
VIXHDR.SAI   for displaying grey scale and halftone pictures on data disc.
		an extension for the display routines in DDSUB.SAI[GRA,HPM]

	requires: PIXHDR.SAI[VIS],DDHDR.SAI[GRA],VIXFAI.REL[VIS],VIXSAI.REL[VIS]

	provides: VIDEO(X1,Y1,X2,Y2,PICTURE,BIT);
        	  VID(X1,Y1,X2,Y2,PICTURE,BIT);
			display PICTURE between X1,Y1,X2,Y2 in SCREEN
			co-ordinates. If BIT=-1 then a fast, low quality
			halftone, if -2 then a high quality halftone, if
			-3 then a buggy halftone. If positive then BIT
			represents a bit mask, which is anded with each
			pixel. If the result is nonzero, a bit is turned
			on in the corresponding part of the display.

		   VIDONE(PICTURE,BT,I(0),J(0));
			similar to VID but faster and simpler. Maps picture
			elements one to one to data disc points. Upper left
			corner of picture is placed I physical DD scanlines
			from the top of the picture, and indented J DD
			elements from the left. Complements the masked bit
			instead of setting it to one.

		   VIDFOR(PICTURE,BUF8,BUF4,BUF2,BUF1,I(0),J(0));
			Like VIDONE, but for 4 bit pictures and four DD buffers.
			Sets up all buffers at once, clearind displayed area
			and inverting bits for compatibility with the inverted
			gray code produced by TVRAW.

		   VIDFRX(PICTURE,BUF8,BUF4,BUF2,BUF1,I(0),J(0));
			Like VIDFOR, but makes a picture twice as wide and tall.
			One picture pixel → 4 DD pixels.

The following routines are for inserting XGP font characters into pictures.

		   FNTSEL(FNTNUM,FILSPEC,FNTHEAD);
			define font number FNTNUM to be font FILSPEC.
			FNTHEAD is the first word of an array '204 words
			long which must be reserved for this font.

                   MARSET(LMAR,YB(100),XB(100));
			set LMAR (for carriage returns) and offset the display
			YB vertically and XB horizontally.

		   CHRDEP(FNTNUM,TEXT,PIC,YLO,XLO,YCOMP,XCOMP);
			add string TEXT to the picture PIC in font # FNTNUM
			starting at position YLO, XLO (may be altered by routine)
			compressed by YCOMP in Y and XCOMP in X.

		   CHRPED(FNTNUM,TEXT,PIC,YLO,XLO,YCOMP,XCOMP);
			add TEXT to PIC, sideways, writing bottom to top.
			X and Y positions and compressions refer to text,
			not picture, reference system.

		   FCACHE(BUFFER,BUFSIZ);
			set up a buffer for caching letter descriptions.
			Doing this greatly speeds up CHRDEP. 5 or 10 K
			is a good buffer size.

		  Defines FNTHIG, position in FNTHEAD where height is stored,
                  and FNTBAS, where baseline is stored.
Internal picture array format

	WORD		CONTENTS
	
	0		PCLN   number of scanlines in the picture
	1		PCWD   words in the pixel portion of the picture
	2		PCBY   valid bytes in the picture
	3		PCBYA  bytes in the picture, including null
				bytes at end of each scanline

	4		LNWD   words per scanline
	5		LNBY   valid bytes per scanline
	6		LNBYA  bytes per scanline, including the nulls

	7		WDBY   bytes per word
	8		WDBI   bits in the valid portion of each word

	9		BYBI   bits per byte

	10		BMAX   2↑BYBI-1, the maximum value of a byte

	11		BPTAB  address of SECOND entry in byte pointer
				table 12+PCLN+address of array

	12 to 11+PCLN	LINTAB table containg the actual address of the first
				word of each scanline, in obvious order

	12+PCLN to 	table containing byte pointers to samples within
	 12+PCLN+LNBYA		lines, to be added to line address.
				The first entry, when ILDB'ed causes
				loading of the first byte in the line.

	13+PCLN+LNBYA to	the picture
	 12+PCLN+LNBYA+PCWD